---
description: Keep a Changelog
title: Keep a Changelog
language: nl
version: 1.0.0
---

- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md"
- gh = "https://github.com/olivierlacan/keep-a-changelog"
- issues = "https://github.com/olivierlacan/keep-a-changelog/issues"
- semver = "https://semver.org/"
- shields = "https://shields.io/"
- thechangelog = "https://changelog.com/podcast/127"
- vandamme = "https://github.com/tech-angels/vandamme/"
- iso = "http://www.iso.org/iso/home/standards/iso8601.htm"
- ghr = "https://help.github.com/articles/creating-releases/"

.header
  .title
    %h1 Houd een Changelog bij
    %h2 Laat je vrienden geen git logs in changelogs dumpen.

  = link_to changelog do
    Versie
    %strong= current_page.metadata[:page][:version]

  %pre.changelog= File.read("CHANGELOG.md")

.answers
  %h3#what
    %a.anchor{ href: "#what", aria_hidden: "true" }
    Wat is een changelog?

  %p
    Een changelog is een bestand met een zorgvuldig samengestelde, chronologische lijst
    van noemenswaardige aanpassingen voor elke versie van een project.

  %h3#why
    %a.anchor{ href: "#why", aria_hidden: "true" }
    Waarom een changelog bijhouden?

  %p
    Om het makkelijker te maken voor gebruikers en programmeurs om precies te zien welke
    noemenswaardige aanpassingen er gedaan zijn tussen elke release (of versie) van het project.

  %h3#who
    %a.anchor{ href: "#who", aria_hidden: "true" }
    Wie heeft een changelog nodig?

  %p
    Mensen hebben het nodig. Of het nu consumenten of ontwikkelaars zijn, eindgebruikers van
    software zijn mensen die er om geven wat er in de software zit die ze gebruiken.
    Als de software verandert, wil men weten wat en hoe.

.good-practices
  %h3#how
    %a.anchor{ href: "#how", aria_hidden: "true" }
    Hoe maak ik een goed changelog?

  %h4#principles
    %a.anchor{ href: "#principles", aria_hidden: "true" }
    Richtlijnen

  %ul
    %li
      Changelogs zijn <em>voor mensen</em>, niet voor machines.
    %li
      Er zou een vermelding moeten zijn voor elke versie.
    %li
      Aanpassingen van het zelfde type moeten gegroepeerd worden.
    %li
      Versies en secties zouden linkbaar moeten zijn.
    %li
      De laatste versie staat bovenaan.
    %li
      De release datum van elke versie word weergegeven.
    %li
      Geef aan of je #{link_to "Semantic Versioning", semver} gebruikt.

  %a.anchor{ href: "#types", aria_hidden: "true" }
  %h4#types Types of changes

  %ul
    %li
      %code Added
      voor nieuwe functionaliteit.
    %li
      %code Changed
      voor aanpassingen aan bestaande functionaliteit.
    %li
      %code Deprecated
      voor functionaliteit die binnenkort komt te vervallen.
    %li
      %code Removed
      voor functionaliteit die vanaf nu vervallen is.
    %li
      %code Fixed
      voor bug fixes.
    %li
      %code Security
      voor aanpassingen met betrekking tot veiligheid.

.effort

  %h3#effort
    %a.anchor{ href: "#effort", aria_hidden: "true" }
    Hoe kan ik, met zo min mogelijk moeite, een changelog bij houden?

  %p
    Houd bovenin een <code>Unreleased</code> sectie bij met aanpassingen voor de komende release.

  %p Dit heeft twee doelen:

  %ul
    %li
      Mensen kunnen zien wat te verwachten in de aankomende release.
    %li
      Als je een release doet kan je eenvoudig de <code>Unreleased</code> sectie
      aanpassen naar een nieuwe release sectie.

.bad-practices
  %h3#bad-practices
    %a.anchor{ href: "#bad-practices", aria_hidden: "true" }
    Kan een changelog slecht zijn?

  %p Ja. Hier een paar manieren waarop je een changelog behoorlijk onbruikbaar kan maken.

  %h4#log-diffs
    %a.anchor{ href: "#log-diffs", aria_hidden: "true" }
    Commit log diffs

  %p
    Commit log diffs gebruiken als een changelog is een slecht idee:
    ze staan vol met ruis. Denk bijvoorbeeld aan merge commits, commits met
    onduidelijke titels, documentatie aanpassingen etc.

  %p
    Het doel van een commit bericht is om één enkele stap in de evolutie van de
    code te beschrijven.

  %p
    Het doel van een changelog is om noemenswaardige aanpassingen te documenteren,
    vaak over meerdere commits, en om deze duidelijk naar de eindgebruiker te communiceren.

  %h4#ignoring-deprecations
    %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
    Deprecations negeren

  %p
    Wanneer mensen upgraden van de ene naar de andere versie,
    moet het overduidelijk zijn als er iets niet meer zal werken.
    Het moet mogelijk zijn om te upgraden naar een versie met deprecations,
    vervolgens de deprecations weg te halen, en vervolgens
    de upgrade kunnen doen naar de versie waar de deprecations removals zijn geworden.

  %p
    Geef altijd op zijn minst de deprecations, removals en changes met grote impact aan in je changelog.

  %h4#confusing-dates
    %a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
    Verwarrende datums

  %p
    Datum notaties verschillen van land tot land, en het is vaak moeilijk om
    een notatie te vinden die makkelijk te lezen is en intuïtief is voor iedereen.

    Het voordeel van de notatie <code>2017-07-17</code> is dat het jaar, maand en dag
    op volgorde van grootte laat zien. Daarom, en het feit dat dit een  #{link_to "ISO standaard", iso}
    is, is dit de aanbevolen datum notatie voor changelog releases.

  %aside
    Dit is niet alles. Help mij antipatterns te verzamelen door
    = link_to "een issue", issues
    of een pull request aan te maken.

.frequently-asked-questions
  %h3#frequently-asked-questions
    %a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
    Veel Gestelde Vragen

  %h4#standard
    %a.anchor{ href: "#standard", aria_hidden: "true" }
    Is er een standaard changelog template?

  %p
    Niet echt. Er is de GNU changelog style guide, en het twee paragrafen lange GNU NEWS bestand "richtlijnen".
    Beiden zijn niet volledig genoeg.

  %p
    Dit project poogt
    = link_to "een betere changelog standaard", changelog
    te creëren. Dit op basis van "good practices" uit de open source wereld.

  %p
    Opbouwende kritiek, discussie en suggesties voor verbetering
    = link_to "zijn welkom.", issues


  %h4#filename
    %a.anchor{ href: "#filename", aria_hidden: "true" }
    Wat zou de changelog bestandsnaam moeten zijn?

  %p
    Noem het <code>CHANGELOG.md</code>. Sommige projecten gebruiken
    <code>HISTORY</code>, <code>NEWS</code> of <code>RELEASES</code>.

  %p
    Je kan denken dat de bestandsnaam niet heel belangrijk is,
    maar waarom zou je het de eindgebruikers moeilijker maken om de changelog te vinden?

  %h4#github-releases
    %a.anchor{ href: "#github-releases", aria_hidden: "true" }
    Wat denk je van GitHub Releases?

  %p
    Het is een goed initiatief. #{link_to "Releases", ghr} kan gebruikt worden
    om simpele git tags (bijvoorbeeld een tag met de naam  <code>v1.0.0</code>)
    te veranderen in uitgebreide release notes door deze handmatig toe te voegen of
    door geannoteerde git tag berichten te gebruiken om release notes te genereren.

  %p
    GitHub Releases maken changelog wat alleen getoond kan worden aan gebruikers
    binnen de context van GitHub. Het is mogelijk om deze dicht bij het format
    te krijgen wat wij hier promoten, maar er zal iets meer werk voor nodig zijn.

  %p
    De huidige versie van GitHub releases is naar mijn mening niet
    echt goed vindbaar voor gebruikers, in tegenstelling tot de typische
    bestanden die in een naam in hoofdletters hebben
    (<code>README</code>, <code>CONTRIBUTING</code>, etc.).
    Een ander knelpunt is dat de interface geen links toestaat naar
    commit logs van elke release.

  %h4#automatic
    %a.anchor{ href: "#automatic", aria_hidden: "true" }
    Kunnen changelogs automatisch geparsed worden?

  %p
    Dat is lastig, mensen gebruiken immers veel verschillende formats en bestandsnamen.

  %p
    #{link_to "Vandamme", vandamme} is een Ruby gem van het
    Gemnasium team wat de changelogs van veel (maar niet alle)
    open source projecten kan parsen.


  %h4#yanked
    %a.anchor{ href: "#yanked", aria_hidden: "true" }
    Wat doen we met teruggetrokken (yanked) releases?

  %p
    Teruggetrokken releases zijn versies die teruggetrokken zijn als gevolg
    van een serieuze bug of beveiligings probleem. Vaak zijn ze niet eens te zien in
    de changelogs. Dat zou wel moeten. Zo zou je een teruggetrokken release moeten tonen:

  %p <code>## [0.0.5] - 2014-12-13 [YANKED]</code>

  %p
    De <code>[YANKED]</code> tag is in hoofdletters voor een reden. Het is belangrijk
    dat mensen dit zien. Omdat het tussen blokhaken genoteerd is, is het ook makkelijker
    automatisch te parsen.


  %h4#rewrite
    %a.anchor{ href: "#rewrite", aria_hidden: "true" }
    Mag je een changelog aanpassen/herschrijven?

  %p
    Natuurlijk. Er zijn goede redenen om een changelog te verbeteren.
    Ik open regelmatig een pull request om missende releases toe te
    voegen aan open source projecten met een slecht onderhouden changelog.

  %p
    Het kan ook zo zijn dat je ontdekt dat je een belangrijke aanpassing niet
    vermeld hebt in je changelog. Het is dan natuurlijk zaak om dit alsnog
    in je changelog te vermelden.

  %h4#contribute
    %a.anchor{ href: "#contribute", aria_hidden: "true" }
    Hoe kan ik bijdragen?

  %p
    Dit document is niet de <strong>waarheid</strong>; het is mijn
    weloverwogen mening, samen met wat informatie en voorbeelden die ik verzameld heb.

  %p
    Dit heb ik gedaan omdat ik wil dat de programmeer gemeenschap een consensus bereikt.
    Ik denk dat de discussie net zo belangrijk is als het eindresultaat.

  %p
    Dus <strong>#{link_to "alle hulp is welkom", gh}</strong>.

.press
  %h3 Conversaties
  %p
    Ik was te gast bij #{link_to "The Changelog podcast", thechangelog} om te praten over
    waarom een changelog belangrijk is programmeurs, en over mijn motivatie achter dit project.
